Read Me for SAM 128

SAM 128 (c) Copyright 2015, 2016 H2Obsession <hydradix@yahoo.com>
Based on SAM for the Commodore 64 (c) 1982 Don't Ask

I grant permission to use or modify the binary code
for any purpose as long as the files are not modified in any way,
and the program using the binary file(s) display(s) the above copyright notice
in the final program (preferably) or at least included in the program's documentation.

I grant permission to use or modify the source code
for any purpose as long as the files are not modified in any way,
or if any files are modified, each must include a notice
stating changes have been made, by whom, and when.
If the source code is not freely available, then the above copyright notice
must be displayed by any program which uses the source code (preferably)
or at least must be included in the program's documentation.

Because the original software, on which my work is based,
is considered abandon-ware, the legality of copyright or other intellectual property rights
is not clear and may vary by jurisdiction.
You should consult with an attorney before using this software in a commercial product.

Also, as demo/bonus, a BASIC program called Green Eggs & Ham is included.
This is a text version of the classic Dr Seuss book by the same name.
I believe the copyright is 1960, but I am not sure who the copyright holder is.
In any case, you should not include that with a commercial distribution
unless you get permission from the actual copyright holder.

-------------------------------
SAM 128 - "Food Wedge" Download
-------------------------------
This distribution is in a .ZIP file, and should include the following:
	BIN (directory)
		sam+reciter.bin (C128 ML, SAM + Reciter)
		sam+resy.lst (listing of address assignments for the ML)
		wedge.bin (C128 ML)
		wedge.lst (listing of address assignments for the ML)
	SRC (directory)
		fast-slow.bas (C128 BASIC program)
		GreenEggsHam.bas (C128 BASIC program)
		quick start.bas (C128 BASIC program)
		SAM+Reciter.src (6502 source)
		super demo.bas (C128 BASIC program)
		UnicoEggs.txt (ASCII text of "Green Eggs and Ham")
		Wedge.src (6502 source)
	ReadMe.txt (this file)
	SAM128E.D64 (1541 disk image with ML and BASIC programs)

-----------------------------
Files on the disk image (d64)
-----------------------------
A quick description of the files on disk (assuming upper/graphic font of C128):

	QUICK START - loads SAM+Reciter and the BASIC wedge; installs both
	SAM128.BIN - ML program that renders only phonemes (uses 10K of BANK 1)
	RECITER128.BIN - ML program that renders English (uses 16K of BANK 1)
	WEDGE.BIN - ML program to easily call SAM or Reciter from BASIC (uses another 1K of BANK 1)
	SUPER DEMO - BASIC program that demonstrates many features of SAM/Reciter (from C64 disk)
	GREEN EGGS & HAM - BASIC program that reads the classic story by Dr. Suess
	FAST-SLOW - BASIC program that shows changing (and reporting of) CPU speed 
	JOKE DEMO - BASIC program that shows 'smart' loading of SAM and Wedge

If you just want to play around with SAM/Reciter in BASIC,
then the first thing you should do after power-up (or reset)
is to RUN the first program, "QUICK START".  It would install both SAM and Reciter
for use with ML programs, and install the WEDGE for use with BASIC.
After running this program, you can run any SAM/Reciter program for the C128
(for example, GREEN EGGS & HAM).

The QUICK START is very simple, as you can see if you LIST it.
You may wonder why it looks-up the current disk unit twice!
This is because the Install routine for both SAM+Reciter and Wedge
clear BASIC variables... so after SAM+Reciter is installed,
the disk unit must be PEEKed again (the previous assignment was cleared).

IMPORTANT: Do not try to run QUICK START again (unless you reset the computer)!
If you do, multiple versions of WEDGE will be installed and usually crash the system
(or at least, make it run much slower than normal).

The three BASIC programs ("SUPER DEMO", "GREEN EGGS & HAM", and "FAST-SLOW") require that
that both SAM+Reciter and Wedge have been installed.  If not, they will generate SYNTAX ERROR.  On the other hand, the "JOKE DEMO" will install Reciter and the BASIC Wedge if neccessary.

The SUPER DEMO is copied (or rather ported) from the C64 version.  It gives you 4 options when run:
	1. Introduction (SAM just talks about himself; demonstrates different speech effects)
	2. KNOBS demo (demonstrates various settings of KNOBS, PITCH, and SPEED)
	3. S.A.M. Sings (SAM sings the U.S.A. national anthem... rather poorly)
	4. Back to BASIC (quit the demo)
	
This is a pretty good program to analyze for ideas in your own BASIC programs.

The GREEN EGGS & HAM is demo that also requires both SAM+Reciter and Wedge to be installed.
If not, this BASIC program will generate a SYNTAX ERROR when RUN.
This program just reads aloud the classic children's book Green Eggs and Ham by Dr. Seuss.
shows a method you may want to use in your in own programs.

The FAST-SLOW program shows that you should (normally) use ]CPUFIX if you change the CPU speed.
If you change CPU speed *without* calling ]CPUFIX, then SAM/Reciter may sound "wrong".
Note: you don't have to call ]CPUFIX everytime you change CPU settings,
but you should call it before trying to ]SAY anything (if you have changed CPU settings).
Note: You can change CPU speed with BASIC commands FAST and SLOW... or by SCPU enable/disable.

The main purpose of "JOKE DEMO" is to show dynamic loading of Reciter and Wedge modules.  Once the modules are installed, it is a very simple Reciter program... with an optional lame joke for your amusement (or confusion).

(BASIC users may ignore the rest of this section)

There are 3 machine language (ML) programs on disk.  All 3 of them run in BANK 1 of the C128.
BASIC users can ignore them (just use the FAST START program which will load and install them).
For ML users, you need to load them into BANK 1 at their default load address (and then install them).
In BASIC, you would do something like this:
	BLOAD"filename",B1,Ux
	BANK 1: SYS install
where x is the disk unit (often 8), and 'install' is either $ee00 (for SAM128.BIN or RECITER128.BIN)
or else $4000 (for WEDGE.BIN).  In ML, you would need to call appropriate KERNAL routines instead.

The first is SAM128.BIN.  This is the minimum you need if you want speech in your program.
It uses BANK 1 RAM from $D800 ~ $FEFF while working (between calls to SAM, $D800~$DBFF and $F700~$FEFF are free).
Although it uses the least amount of RAM, it can only speak with SAM's special phonetic language...
it does *not* understand English!  (However, SAM is more customizable than Reciter)

The second is RECITER128.BIN.  This is what you want if you need English text-to-speech,
but you don't need a BASIC interface.  It uses BANK 1 RAM from $C000 ~ $FEFF while working
(between calls to Reciter, $D800~$DBFF and $F700~$FEFF are free).

The last is WEDGE.BIN.  This ML code loads into $4000 BANK 1 (and the 'install' is also at $4000).
However this is a bit complicated, because its job is to link BASIC with the ML programs discussed above.
When you call 'install', it WEDGE will relocate itself 3 pages ($300 = 768 bytes) below the current TOP-OF-RAM1.
This assumes the current TOP-OF-RAM1 is an even page boundary... if not, it could be up to $3FF (1023) bytes below.

For example (after reset) if you install SAM128.BIN, the TOP-OF-RAM1 will be set to $D800.
If you then load and install WEDGE.BIN, it will relocate itself to the area $D500~$D7FF
(and set the TOP-OF-RAM1 to $D500).

For example (after reset) if you install RECITER128.BIN, the TOP-OF-RAM1 will be set to $C000.
If you then load and install WEDGE.BIN, it will relocate itself to the area $BD00~$BFFF
(and set the TOP-OF-RAM1 to $BD00).

Besides relocating itself in RAM 1, the Wedge will also install a few small 'stub programs' in Common RAM.
Sadly, there is no safe place in Common RAM that is unused by BASIC 7(ROM), KERNAL, and the popular
extensions BASIC 7.1, BASIC 7.80, and/or BASIC 8.  So WEDGE installs stubs in a rarely-used area.
It installs a 'permanent' stub at $14B~$150 (call Wedge)... this area of the CPU stack is never directly used by BASIC,
and if an IRQ occurs when BASIC is using 'max stack' it should also be safe.
But, if BASIC is using 'max stack', and an IRQ occurs, and then an NMI occurs (before the IRQ finishes),
then this stub could be destroyed!  Impossible if not using NMI-type software (like RS-232)... and even then,
could only happen with worst-case (maximum BASIC use) of the CPU stack.
Another 'permanent' stub at $138~$13D (exit Wedge) is installed.  This area should be safe
unless you are loading from cassette, and the cassette has many errors in a single block
(the stub is at the end of the 'cassette error log').

The region between $13E and $14A is not used by Wedge (but is used by BASIC 7.80).
The region between $12E and $137 is used temporarily by Wedge (should not cause any problems, because it is temporary).

---------------------------
  Using SAM / Reciter 128
---------------------------
SAM (and Reciter) are text-to-speech programs.  Their operation is too complex to fully describe in this READ-ME file.
Complete documentation is available on my website at http://sites.google.com/site/h2obsession/CBM/C128/SAM-128

However, I will give a VERY brief summary for those who use the Wedge (or "FAST START").
First, all new commands added by Wedge start with a right-bracket character, "]"
The new commands are:
	]CPUFIX -- adjusts voice for 1MHz/2MHz/20MHz CPU speed (SLOW/FAST/SuperCPU)
	]ERROR -- display SAM phonemes of most recent string, highlight first error (if any)
	]KNOBS f1_scale, f2_scale -- change sound factors 1 and 2 for most phonemes (each 1~255, default 128)
	]LIGHTS show -- enables VIC-II screen during speech if 'show' is non-zero (0~255, default 0)
	]NOISES t1, t2 -- sets time period for some 'noisy' phonemes (each 1~255, default depends on CPU)
	]PHONES -- displays SAM's translation of phonemes into phones
	]PITCH value -- sets base wavelength of speech (lower values = higher frequency! default 64)
	]QUIT -- uninstalls the BASIC Wedge (clears all BASIC variables!)
	]RECITER -- enables English-to-speech Engine (only if Reciter.bin has been installed)
	]SAM -- enables phoneme-to-speech Engine
	]SAY string_expression -- main command, any BASIC string expression may be used (literal, variable, equation)
	]SPEED value -- sets base phone duration (lower values = higher speed! default 72)
	]TIMEBASE value -- set time period for typical phonemes (lower values = higher pitch!, default depends on CPU)
	
]SAY is the most used... it requires a string argument.  If Reciter is active, then any string argument is acceptable
(in which case, the argument should be English text).
If, instead, SAM is active then the argument must be a valid string of SAM phonemes (otherwise you will hear "beep-beep").

]SAM and ]RECITER are used to switch the Wedge between phoneme-speech (SAM) or English-speech (Reciter).

]PITCH and ]SPEED are easy ways to changes voice quality (independent of CPU speed)

]KNOBS is a more advance way to change voice quality (also independent of CPU speed)

]ERROR and ]PHONES are useful for debugging (show phonemes [highlight any error] and show phones... respectively)

]NOISES and ]TIMEBASE are advanced ways to change voice quality (very dependent on CPU speed!)

]CPUFIX will set default values of NOISES and TIMEBASE, according to active CPU speed (1MHz, 2MHz, or 20MHz)
	and according to machine type (NTSC/PAL).

]LIGHTS and ]QUIT are almost never used.

